/**********************************************************************************************************************
 * @file    ubuff.h
 * @author  Queclink Hubert.Lee
 * @date    2016-12-15
 * @brief   Universal Buffer Operation Interface.
 * @ingroup hdl
 * Copyright (C) 2016 Queclink Wireless Solutions (ShenZhen) Co., Ltd. All Rights Reserved.
 *
 * @attention
 *
 * @usage
 *
 *********************************************************************************************************************/


#ifndef __UBUFF_H
#define __UBUFF_H

/* includes ---------------------------------------------------------------------------------------------------------*/
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif


#ifndef _SSIZE_T
#define _SSIZE_T
typedef signed int ssize_t;
#endif /* _SSIZE_T */

/*
 * @brief  Register a buffer to operate.
 * @param  buf: [I], the base address of buffer;
 *         size: [I], the size of buffer;
 * @retval -1:failed, others:buffer id of registered.
 */
int ubuff_register(const void *buf, size_t size);

/*
 * @brief  Write data into buffer.
 * @param  id: [I], buffer id;
 *         buf: [I], the data to write;
 *         count: [I], the number of bytes to write;
 * @retval -1:failed, others:the number of bytes actually written into buffer.
 */
ssize_t ubuff_write(int id, const void *buf, size_t count);

/*
 * @brief  Read data from buffer.
 * @param  id: [I], buffer id;
 *         buf: [O], The read data;
 *         count: [I], the number of bytes to read;
 * @retval -1:failed, others:the number of bytes actually read from buffer.
 */
ssize_t ubuff_read(int id, void *buf, size_t count);

/*
 * @brief  Read data from buffer but don't drop them.
 * @note   Just read, don't delete data.
 * @param  id: [I], buffer id;
 *         buf: [O], The read data;
 *         count: [I], the number of bytes to read;
 * @retval -1:failed, others:the number of bytes actually read from buffer.
 */
ssize_t ubuff_read_dummy(int id, void *buf, size_t count);

/*
 * @brief  Get the number of bytes of user data in the buffer.
 * @param  id: [I], buffer id;
 * @retval the number of bytes of user data.
 */
size_t ubuff_data_size(int id);

/*
 * @brief  Get the number of bytes of invalid data in the buffer.
 * @param  id: [I], buffer id;
 * @retval the number of bytes of invalid data.
 */
size_t ubuff_empty_size(int id);

/*
 * @brief  Clear all data of a buffer.
 * @param  buf: [I], the base address of buffer;
 * @retval 0:success, -1:failed.
 */
int ubuff_clear(int id);

/*
 * @brief  Unregister a buffer.
 * @param  id: [I], buffer id;
 * @retval 0:success, -1:failed.
 */
int ubuff_unregister(int id);

struct ubuffer {
    int     id;     /* buffer id */
    void    *buf;   /* the base address of buffer */
    size_t  size;   /* the size of buffer */
};


#ifdef __cplusplus
}
#endif

#endif /* __UBUFF_H */